<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta name="generator" content=
  "HTML Tidy for Mac OS X (vers 1 September 2005), see www.w3.org" />

  <title>Component Adapters</title>
</head>

<body>
  <h3>What Are <a href=
  "http://www.picocontainer.org/javadoc/core/org/picocontainer/ComponentAdapter.html">
  ComponentAdapters</a> and why are they useful?</h3>

  <p>ComponentAdapters are probably PicoContainer's most highly
  misunderstood (and coincidentally, most powerful) feature. They
  combine the power of an object factory, and an object interceptor
  rolled into one.</p>

  <p>The key to the component adapter is only one method:</p>

  <div class="source">
    <pre>
T getComponentInstance(PicoContainer container, Type into) throws PicoCompositionException
</pre>
  </div>

  <p>In essence, the sole purpose of the ComponentAdapter is to
  provide a PicoContainer with an actual object instance. In fact,
  <a href=
  "http://www.picocontainer.org/javadoc/core/org/picocontainer/DefaultPicoContainer.html">
  DefaultPicoContainer</a> does not contain a Map of Classes, a Map
  of object Instances, or anything like that. Instead <strong>it contains a
  map of ComponentAdapters</strong>.</p>

  <p>Each time you use addComponent(..) on PicoContainer, behind
  the scenes a new ComponentAdapter instance is set up. There is
  one ComponentAdapter implementation per component instance. The
  ComponentAdapters can be added to a container directly, or made
  by the ComponentFactory the container is using. Both for
  BehaviorFactory and InjectionFactory implementations. Its all
  hidden from you to make PicoContainer's API appear simple.</p>

  <h3>Call Order</h3>

  <p>So what happens when PicoContainer.getComponent() is
  called?</p>

  <p><img src="images/componentAdapterSequence.png" alt=
  "ComponentAdapter Invocation Sequence" title=
  "Component Adapter invocation sequence." /></p>

  <p>Our goal with this sequence diagram is to show that the
  primary function of PicoContainer here is to locate the
  ComponentAdapter that has been previously registered via <a href=
  "http://www.picocontainer.org/javadoc/core/org/picocontainer/MutablePicoContainer.html">
  MutablePicoContainer</a>.addComponent() or
  MutablePicoContainer.addAdapter().</p>

  <h3>Instantiation and <a href=
  "http://www.picocontainer.org/javadoc/core/org/picocontainer/Injector.html">
  Injectors</a></h3>

  <p>Once PicoContainer locates the appropriate ComponentAdapter,
  it calls the fabled
  <strong>ComponentAdapter.getComponentInstance()</strong>. A very
  simple ComponentAdapter could merely call Class.newInstance() on
  the type of the component being instantiated. Of course,
  PicoContainer may be small, but it is hardly simple!</p>

  <p>PicoContainer provides different ways of instantiating a
  component through different Injectors. The Injector interface
  extends ComponentAdapter with some additional services.
  Implementations of Injectors provide the actual methods of
  injecting Dependencies. (The reason we first came to discover
  PicoContainer in the first place!)</p>

  <p>The two most popular methods of injecting dependencies are:
  <a href=
  "http://www.picocontainer.org/javadoc/core/org/picocontainer/injectors/SetterInjector.html">
  SetterInjector</a>, and <a href=
  "http://www.picocontainer.org/javadoc/core/org/picocontainer/injectors/ConstructorInjector.html">
  ConstructorInjector</a>. However, PicoContainer provides other
  injectors that go beyond the scope of this article. However, just
  remember that under the hood. If you have code:</p>

  <div class="source">
    <pre>
MutablePicoContainer pico = new PicoBuilder().withCDI().build(); //withCDI indicates: Pico: use ConstructorInjector
pico.addComponent(MyObject.class);
//... More goes by
    MyObject instance = pico.getComponent(MyObject.class);
</pre>
  </div>

  <p>That whenever you call addComponent(), Pico, behind the
  scenes, is wrapping MyObject.class with a ConstructorInjector
  ComponentAdapter. When you call Pico.getComponent(),
  PicoContainer calls the ConstructorInjector, which in turns, uses
  ConstructorInjection to create the MyObject instance.</p>

  <h3>Post Instantiation Modification using <a href=
  "http://www.picocontainer.org/javadoc/core/org/picocontainer/Behavior.html">
  Behaviors</a>.</h3>

  <p>If the only job of a ComponentAdapter was to construct an
  object, we would probably call it a <em>ComponentFactory</em> and
  be done with it. However, as you are most assuredly an astute
  reader, you can clearly tell that since there is more scrollbar
  left on your browser.... there is more to this story.</p>

  <p>You see, ComponentAdapters were meant to be <em>chained</em>
  together using the Decorator pattern. It is this chaining that
  allows for the "Post Processing" step that is listed on the
  sequence diagram. There are many things that can be done to an
  object once it is created.</p>

  <p>For example, maybe you don't want a new object instance to be
  created each and every time you call PicoContainer.getInstance().
  Perhaps you want an object to be stateless and shared across
  multiple objects? (The Spring Framework, and Guice calls this behavior
  Singleton).</p>

  <p>In this case, you would insert in a "Component Adapter Chain",
  the <a href=
  "http://www.picocontainer.org/javadoc/core/org/picocontainer/behaviors/Caching.html">
  Caching</a> behavior, so the ComponentAdapter Chain looked like
  this:</p>
  <pre>
Caching -&gt; ConstructorInjector
</pre>

  <p>With an adapter chain like this, the first time
  PicoContainer.getInstance() is called, Caching would pass the
  request down to ConstructorInjector. Once it receives the
  instance returned back, it would store that instance for future
  calls and return that instance back to the caller. Upon future
  calls, Caching would return its own <em>cached</em> instance.
  (Thus the name Caching ComponentAdapter instead of
  SingletonComponentAdapter). Of course, other storage options are
  possible: HttpSession, ThreadLocal, etc.</p>

  <p>Also keep in mind that behaviors are not limited to how an
  object is stored. For example <a href=
  "http://www.picocontainer.org/javadoc/core/org/picocontainer/behaviors/HiddenImplementation.html">
  HiddenImplementation</a> wraps the instantiated component in a
  dynamic proxy, thereby enforcing that receiver of that component
  cannot cast the received interface into an implementation.</p>

  <h3>Using ComponentAdapter directly.</h3>

  <p>Some examples :</p>

  <div class="source">
    <pre>
public class MyAdapter extends AbstractAdapter {
    private QuantumEntanglement qe = new QuantumEntanglementImpl();
    public MyAdapter() {
        super(QuantumEntanglement.class, QuantumEntanglementImpl.class);
    }
    public Object getComponent(PicoContainer pico) {
        Auditor a = pico.getComponent(Auditor.class);
        a.audit("QE used", new Date());
        return qe;
    }
    public void verify(PicoContainer container) {
    }
}
...
pico = new DefaultPicoContainer();
pico.addAdapter(new MyAdapter()); 
QuantumEntanglement e = pico.getComponent(QuantumEntanglement.class);
</pre>
  </div>

  <h3>Changing the default ComponentAdapter for a new
  PicoContainer</h3>

  <h4>The easy way:</h4>

  <p>PicoContainer 2.0 has provided a Builder class series to help
  define which ComponntAdapter to use with a given container by
  default. There are different builders with each subproject. So
  PicoContainer has <a href=
  "http://www.picocontainer.org/javadoc/core/org/picocontainer/PicoBuilder.html">
  PicoBuilder</a>, PicoContainer-Gems has <a href=
  "http://www.picocontainer.org/javadoc/gems/org/picocontainer/gems/PicoGemsBuilder.html">
  PicoGemsBuilder</a>, and so on. For the purpose of clarity, we
  will only use PicoBuilder in this document.</p>

  <p>Example 1: Caching Behaviors</p>

  <div class="source">
    <pre>
pico = new PicoBuilder().withCaching().build();
</pre>
  </div>

  <p>Example 2: Caching + ImplementationHiding (same imports)</p>

  <div class="source">
    <pre>
pico = new PicoBuilder().withCaching().withHiddenImplementations().build();
</pre>
  </div>

  <p>In both of these Examples, ConstructorInjection is
  automatically used by default.</p>

  <p>Example 3: Setter Injection</p>

  <div class="source">
    <pre>
pico = new PicoBuilder().withSDI().build();
</pre>
  </div>

  <h4>The slightly harder (but flexible way)</h4>

  <p>Since there is one ComponentAdapter chain per registration in
  a mutable PicoContainer, there needs to be an object that creates
  a ComponentAdapter every time
  MutablePicoContainer.addComponent() is called. Thus enters the
  ComponentFactories. (Each ComponentFactory creates
  ComponentAdapter).</p>

  <p>The key here is creating the new DefaultPicoContainer with the
  appropriate ComponentFactories</p>

  <p>Example 1: Caching Behaviors:</p>

  <div class="source">
    <pre>
pico = new DefaultPicoContainer(new Caching().wrap(new ConstructorInjection()));
</pre>
  </div>

  <p>Example 2: Caching + Implementation Hiding</p>

  <div class="source">
    <pre>
pico = new DefaultPicoContainer(new Caching().wrap(new ImplementationHiding().wrap(new ConstructorInjection)));
</pre>
  </div>

  <p>Example 3: Setter Injection</p>

  <div class="source">
    <pre>
pico = new DefaultPicoContainer(new SetterInjection());
</pre>
  </div>

  <h3>Changing the default ComponentAdapter when registering
  objects.</h3>

  <p>When you modify behaviors, you are, in essence, swapping the
  default ComponetFactory being used for futher registrations. More
  details about this have been discussed in the section "<a href=
  "behaviors.html">Modifying Behaviors</a>"</p>

  <p>As each ComponentAdapter implementation only does one specific
  job, you can see that it is quite simple, but the range of possibilities are endless.</p>
</body>
</html>
